home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / php / pear / docs / apd / .tmpREADME < prev   
Text File  |  2004-03-24  |  11KB  |  288 lines
  1. PHP-APD
  2. ----------------------------------------------------------------------------- *
  3.  
  4.     Welcome to Version 2 of this README.  If you have read the README
  5.     before, you may want to read it again.  There may be new stuff, 
  6.     particularly regarding how to use the new pprof tracing.
  7.  
  8. Buid/Installation process:
  9. ----------------------------------------------------------------------------- *
  10.  
  11.     Make sure you have installed the CGI version of PHP and it is available
  12.     in your current path along with the phpize script.
  13.  
  14.     Change into the source directory (either created from the downloaded TAR
  15.     archive or from checking out CVS) an run the following commands:
  16.  
  17.         phpize  (not necessary if configure exists)
  18.         ./configure
  19.         make install
  20.  
  21.  
  22.     This automatically should install the 'php_apd' zend module into your
  23.  
  24.         <PHP INSTALL PATH>/lib/php/<ZEND VERSION><-OPTIONAL_DEBUG>/
  25.  
  26.     directory. It isn't mandatory to have it there, in fact you can install
  27.     it anywhere you care.
  28.  
  29.  
  30.     In your INI file, add the following lines:
  31.  
  32.         zend_extension = /absolute/path/to/php_apd.so
  33.         apd.dumpdir = /absolute/path/to/trace/directory
  34.  
  35.     Depending on your PHP build, the zend_extension directive can be one
  36.     of the following:
  37.  
  38.         zend_extension              (non ZTS, non debug build)
  39.         zend_extension_ts           (    ZTS, non debug build)
  40.         zend_extension_debug        (non ZTS,     debug build)
  41.         zend_extension_debug_ts     (    ZTS,     debug build)
  42.  
  43.         zend_extension_debug = /absolute/path/to/php_apd.so
  44.  
  45.     apd.dumpdir:
  46.  
  47.         This can either be an absolute path or a relative path. Relative
  48.         means always relative to your where from you run your executeable.
  49.  
  50.  
  51.     *** NOTE ******************************************************************
  52.     *
  53.     * If you're running the CGI version of PHP, you will need to add the '-e'
  54.     * flag to enable extended information for apd to work properly:
  55.     *
  56.     *     php -e -f script.php
  57.     *
  58.     ***************************************************************************
  59.  
  60.  
  61. Win32ism
  62. ----------------------------------------------------------------------------- *
  63.  
  64.     To build APD under windows you need a working PHP compilation
  65.     environment as described on http://php.net/ (basically, it requires
  66.     you to have MSVC, win32build.zip and bison/flex and some know how
  67.     about how to get it to work). Also make sure that adp.dsp has DOS
  68.     line endings! If it has unix line endings, MSVC will complain about it.
  69.  
  70.     You can use normal Windows path values for your PHP.INI settings:
  71.  
  72.         zend_extension_debug_ts = c:\phpdev\php_apd.dll
  73.         apd.dumpdir = c:\phpdev\traces
  74.  
  75.  
  76. How to use PHP-APD in your scripts with pprof (new style)
  77. ----------------------------------------------------------------------------- *
  78.  
  79.     This section describes the new way that profiling works under apd.  The 
  80.     old method, which generates a non-machine parseable indented output is
  81.     still available (see below), but is debing deprecated in favor of this,
  82.     the pprof output style, which dumps a machine-readable file and provides
  83.     a tool for interpreting the trace.  This allows for much greater specificity
  84.     in the output, allows different sorts of summary generation, and a good
  85.     deal of conrol over the call-tree output.  
  86.  
  87.     To set pprof tracing, just add the following line to the top of your
  88.     phpp script:
  89.  
  90.         apd_set_pprof_trace();
  91.  
  92.     This will generate a pprof.<pid> file in your apd.dumpdir.  The format
  93.     of this file is as follows:
  94.  
  95. ! 1 simple.php
  96. & 1 main 2
  97. + 1 1 2
  98. - 2
  99. & 3 hello 2
  100. + 3 1 9
  101. - 3
  102. & 4 yell 2
  103. + 4 1 9
  104. & 5 strtoupper 1
  105. + 5 1 4
  106. - 5
  107. - 4
  108. - 1
  109.  
  110.  
  111. ! assigns a numeric index to a file so we can easily reference that file later. 
  112. & declares a new function and it's index for the trace.  
  113. + shows a function being entered and the file index and line number it was called on. 
  114. - shows a function being exited. 
  115. @ shows a time elapsed in the form  
  116.     @ process_user_clock_t process_system_clock_t process_real_clock_t
  117.  
  118. The syntax of the file is largely for informational purposes, it's not designed
  119. for human consumption.  To extract human-readable information from the trace, use
  120. the pprofp utility, bundled with APD.  The options to apd are:
  121.  
  122. pprofp <flags> <trace file>
  123.     Sort options
  124.     -a          Sort by alphabetic names of subroutines.
  125.     -l          Sort by number of calls to subroutines
  126.     -r          Sort by real time spent in subroutines.
  127.     -R          Sort by real time spent in subroutines (inclusive of child calls).
  128.     -s          Sort by system time spent in subroutines.
  129.     -S          Sort by system time spent in subroutines (inclusive of child calls).
  130.     -u          Sort by user time spent in subroutines.
  131.     -U          Sort by user time spent in subroutines (inclusive of child calls).
  132.     -v          Sort by average amount of time spent in subroutines.
  133.     -z          Sort by user+system time spent in subroutines. (default)
  134.  
  135.     Display options
  136.     -c          Display Real time elapsed alongside call tree.
  137.     -i          Suppress reporting for php builtin functions
  138.     -O <cnt>    Specifies maximum number of subroutines to display. (default 15)
  139.     -t          Display compressed call tree.
  140.     -T          Display uncompressed call tree
  141.  
  142. Thus, to get basic output on the trace, we would do 
  143.  
  144. pprofp -u /tmp/pprof.<pid>
  145.  
  146. and we get something like:
  147.  
  148. 10:33:29(george@ballista)[~/pear/PECL/apd]> pprofp -u /tmp/pprof.23424
  149.  
  150. Trace for /data/storage/mirrors/www.php.net/index.php
  151. Total Elapsed Time =    0.09
  152. Total System Time  =    0.00
  153. Total User Time    =    0.06
  154.  
  155.  
  156.          Real         User        System             secs/    cumm
  157. %Time (excl/cumm)  (excl/cumm)  (excl/cumm) Calls    call    s/call Name
  158. ------------------------------------------------------------------------
  159.  33.3  0.02  0.02   0.02  0.02   0.00  0.00     7   0.0029    0.00 require_once
  160.  33.3  0.01  0.01   0.02  0.02   0.00  0.00    55   0.0004    0.00 sprintf
  161.  33.3  0.00  0.00   0.02  0.02   0.00  0.00   144   0.0001    0.00 feof
  162.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 htmlspecialchars
  163.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 substr
  164.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 make_submit
  165.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     7   0.0000    0.00 printf
  166.   0.0  0.02  0.02   0.00  0.00   0.00  0.00     6   0.0000    0.00 printf
  167.   0.0  0.02  0.02   0.00  0.00   0.00  0.00     6   0.0000    0.00 getimagesize
  168.   0.0  0.00  0.01   0.00  0.02   0.00  0.00    17   0.0000    0.00 print_link
  169.   0.0  0.00  0.00   0.00  0.00   0.00  0.00    10   0.0000    0.00 delim
  170.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     7   0.0000    0.00 spacer
  171.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     9   0.0000    0.00 hdelim
  172.   0.0  0.00  0.02   0.00  0.01   0.00  0.00     2   0.0000    0.01 download_link
  173.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 mirror_provider_url
  174.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 mirror_provider
  175.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 strftime
  176.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 have_stats
  177.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 commonfooter
  178.   0.0  0.00  0.00   0.00  0.00   0.00  0.00     2   0.0000    0.00 strrchr
  179.   0.0  0.01  0.01   0.00  0.00   0.00  0.00     2   0.0000    0.00 filesize
  180.  
  181. This sorts output based on the usertime spent in subroutines, and ommits a call tree.  If
  182. we added a -t
  183.  
  184. 10:38:30(george@ballista)[~/pear/PECL/apd]> pprofp -u -t /tmp/pprof.23424
  185.  
  186. ...
  187.  
  188. We would also get a call graph for the function.  Which is often very long.
  189.  
  190.  
  191.  
  192.  
  193. How to use PHP-APD in your scripts (old style)
  194. ----------------------------------------------------------------------------- *
  195.  
  196.     In your PHP script, add the following line:
  197.  
  198.         apd_set_session_trace(N);
  199.  
  200.     where N is an integer which is formed by masking together the following
  201.     values:
  202.  
  203.         FUNCTION_TRACE      1
  204.         ARGS_TRACE          2
  205.         ASSIGNMENT_TRACE    4
  206.         STATEMENT_TRACE     8
  207.         MEMORY_TRACE        16
  208.         TIMING_TRACE        32
  209.         SUMMARY_TRACE       64
  210.  
  211.     I would seriously not recommend using MEMORY_TRACE.  It is very slow and
  212.     does not appear to be accurate (great, huh?)  also ASSIGNMENT_TRACE is not
  213.     implemented. So, to turn on all functional traces (TIMING, FUNCTIONS, ARGS
  214.     SUMMARY (like strace -c)) use:
  215.  
  216.         apd_set_session_trace(99);
  217.  
  218.  
  219.     Now run your script.
  220.  
  221.  
  222.     The dump output will be writting to:
  223.  
  224.         <apd.dumpdir>/apd_dump_<pid>
  225.  
  226.     The output itself will look something like:
  227.  
  228. 16:37:51(george@wasabi)[~/src/apd]> cat /tmp/apd_dump_31994 
  229.  
  230.  
  231. APD - Advanced PHP Debugger Trace File
  232. ---------------------------------------------------------------------------
  233. Process Pid (31994)
  234. Trace Begun at Fri Aug 10 16:37:45 2001
  235. ---------------------------------------------------------------------------
  236. (  0.000000): apd_set_session_trace called at somewhere
  237. (  0.001482): apd_set_session_trace() returned.  Elapsed (997475865.364909)
  238. (  0.001563): getcwd() /opt/apache/htdocs/a.php:4
  239. (  0.001628): getcwd() returned.  Elapsed (0.000065)
  240. (  0.001819): require() /opt/apache/htdocs/a.php:6
  241.               ++ argv[0] $(??) = /tmp/a.php
  242. (  0.002231):   getcwd() /tmp/a.php:3
  243. (  0.002290):   getcwd() returned.  Elapsed (0.000059)
  244. (  0.002375):   include_once() /tmp/a.php:4
  245.                 ++ argv[0] $(??) = /tmp/aa.php
  246. (  0.003276):   include_once() returned.  Elapsed (0.000901)
  247. (  0.003334): require() returned.  Elapsed (0.001515)
  248. (  0.003381): require_once() /opt/apache/htdocs/a.php:7
  249.               ++ argv[0] $(??) = /tmp/aa.php
  250. (  0.003515): require_once() returned.  Elapsed (0.000134)
  251. (  0.003564): include() /opt/apache/htdocs/a.php:8
  252.               ++ argv[0] $(??) = /tmp/b.php
  253. (  0.003792): include() returned.  Elapsed (0.000228)
  254. (  0.018341): RSHUTDOWN called - end of trace
  255. ---------------------------------------------------------------------------
  256. Process Pid (31994)
  257. Trace Ended at Fri Aug 10 16:37:45 2001
  258. ---------------------------------------------------------------------------
  259.  
  260.  
  261. Implemented Debugging Functions
  262. ----------------------------------------------------------------------------- *
  263.  
  264.     array apd_callstack()
  265.         Returns the current call stack as an array (very cool).
  266.  
  267.     apd_cluck([string warning[,string line delimiter])
  268.         Behaves like perl's Carp::cluck. Throw a warning and a callstack.
  269.         The default line delimiter is "<BR />\n".
  270.  
  271.     apd_croak([string error[, string line delimiter]])
  272.         Behaves like perl's Carp::croak. Throw an error, a callstack and then
  273.         exit.  The default line delimiter is "<BR />\n".
  274.  
  275.     array apd_dump_regular_resources()
  276.         Return all current regular resources as an array.
  277.  
  278.     array apd_dump_persistent_resources()
  279.         Return all persistent resources as an array.
  280.  
  281.     override_function(string func_name, string func_args, string func_code):
  282.         Syntax similar to create_function(). Overrides built-in functions
  283.         (replaces them in the symbol table).
  284.  
  285.     rename_function(string orig_name, string new_name)
  286.         Renames orig_name to new_name in the global function_table.  Useful
  287.         for temporarly overriding builtin functions.
  288.